Get Signed Document API

This document highlights the Get Signed Document API details.

Description

Objective

The Get Signed Document API retrieves the signed or unsigned document's URL, along with its signing status, expiry status, and any failure reason. It is used to check the status and validity of a document in the signing process.

Input	Output
The document ID and skipBase64 flag to determine the document's base64 encoding status	The document URL (signed/unsigned), signing status, expiry status, and failure reason (if any)

API URL

https://ind-engine.thomas.hyperverge.co/v1/getSignedDocument

API Endpoint

getSignedDocument

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the complete information on all the input parameters for the module.

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
`documentId`	A unique document ID for each signer	Mandatory	Not Applicable	Not Applicable
`serviceId`	The Identifier for the ASP in use	Mandatory	Not Applicable	Not Applicable
`skipBase64`	Mandatory field - true to be passed for all cases	Mandatory	true	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/getSignedDocument' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "documentId": "<Enter_the_document_ID>",
    "serviceId": "<Enter_the_service_ID>"
}'

Success Response

The following is a success response from the API:

{
  "status": "success",
  "statusCode": "200",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "result": {
    "data": {
      "documentId": "<Document_ID>",
      "s3Url": "<Signed_Document_URL>",
      "signed": true,
      "expired": false,
      "userCertDetails": {
        "name": "<Name_of_the_User>",
        "pincode": "<Pincode>",
        "gender": "<Gender>",
        "state": "<State>",
        "title": "<Title>",
        "yob": "<Year_of_Birth>"
      },
      "inviteeDetails": {
        "inviteeName": "<Invitee_Name>",
        "inviteeEmail": "<Invitee_Email>"
      }
    }
  }
}

Success Response Details

The following table highlights the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The status code of the request
metaData	object	Metadata related to the request
metaData.requestId	string	A unique identifier for the request
metaData.transactionId	string	A unique identifier for the transaction
documentId	string	The unique identifier for the document
s3Url	string	The S3 URL containing the signed document
signed	boolean	Indicates whether the document has been signed
expired	boolean	Indicates whether the signed document has expired
name	string	The name of the signer as per Aadhaar
pincode	string	The pincode of the signer as per Aadhaar
gender	string	The gender of the signer as per Aadhaar
state	string	The state of the signer as per Aadhaar
title	string	The last four digits of the signer's Aadhaar number
yob	string	The year of birth of the signer as per Aadhaar
inviteeName	string	The name of the invitee
inviteeEmail	string	The email address of the invitee
failureReason	string	The reason for failure if the status code is not 200

Error Response Samples

The following are some sample error responses from the API.

Input Validation Error
Missing/Invalid Credentials
Internal Server Error

{
  "status": "failure",
  "statusCode": "400",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>",
    "error": {
      "code": "Required file input is missing",
      "message": "The request is missing the mandatory file input"
    }
  },
  "result": {
    "data": {
      "documentId": "<Document_ID>",
      "serviceId": "<Service_ID>",
      "skipBase64": true,
      "failureReason": "<Failure_Reason>"
    }
  }
}

{
  "status": "failure",
  "statusCode": "400",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>",
    "error": {
      "code": "Required file input is missing",
      "message": "The request is missing the mandatory file input"
    }
  },
  "result": {
    "data": {
      "documentId": "<Document_ID>",
      "serviceId": "<Service_ID>",
      "skipBase64": true,
      "failureReason": "<Failure_Reason>"
    }
  }
}

{
  "status": "failure",
  "statusCode": "500",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>",
    "error": {
      "code": "Internal Server Error",
      "message": "Please check the request headers or contact support for resolution"
    }
  },
  "result": {
    "data": {
      "documentId": "<Document_ID>",
      "serviceId": "<Service_ID>",
      "skipBase64": true,
      "failureReason": "<Failure_Reason>"
    }
  }
}

Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	Required file input is missing	The request is missing the mandatory file input
400	Error while parsing file input	An error occurred while parsing the provided file input
400	Document ID not found	The requested document ID could not be found
400	Document Deleted	The requested document has been deleted
404	Document not found	The document could not be found on Leegality's end
500	Unknown error while parsing inputs	The request encountered an unknown error while parsing the inputs
500	Internal Server Error	Please check the request headers or contact support for resolution
500	PDF generation failed	The process of generating the PDF failed
503	External vendor downtime	The external vendor is currently experiencing downtime

Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

Inputs​

Request​

Success Response​

Success Response Details​

Error Response Samples​

Error Response Details​